{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Introduction to atomman: crystal loading\n",
    "\n",
    "__Lucas M. Hale__, [lucas.hale@nist.gov](mailto:lucas.hale@nist.gov?Subject=ipr-demo), _Materials Science and Engineering Division, NIST_.\n",
    "    \n",
    "[Disclaimers](http://www.nist.gov/public_affairs/disclaimer.cfm) "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1. Introduction<a id='section1'></a>\n",
    "\n",
    "The relaxed_crystal records found in the NIST Interatomic Potentials Repository database (https://potentials.nist.gov/) define unit cells for crystal structures that have been relaxed on a per-potential basis. The 'crystal' load option allows Systems to be constructed based on the information in these records.  The information can be loaded either from a local copy of the database or the remote database.  \n",
    "\n",
    "*Updated version 1.4.0.* Query parameters and database options updated to be in line with potentials version 0.3.0."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Library Imports**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "atomman version = 1.4.0\n",
      "Notebook executed on 2021-08-04\n"
     ]
    }
   ],
   "source": [
    "# Standard Python libraries\n",
    "import datetime\n",
    "\n",
    "# http://www.numpy.org/\n",
    "import numpy as np\n",
    "\n",
    "import atomman as am\n",
    "import atomman.unitconvert as uc\n",
    "\n",
    "# Show atomman version\n",
    "print('atomman version =', am.__version__)\n",
    "\n",
    "# Show date of Notebook execution\n",
    "print('Notebook executed on', datetime.date.today())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2. atomman.load('crystal')<a id='section2'></a>\n",
    "\n",
    "Accesses the potentials database to retrieve a relaxed_crystal record and generate a unit cell System based on it.\n",
    "\n",
    "Query parameters\n",
    "\n",
    "- __name__ (*str or list*) The record name(s) to parse by.  For relaxed crystal records, the names should correspond to key.\n",
    "- __key__ (*str or list, optional*) UUID4 key(s) to search for.  Each entry has a unique random-generated UUID4 key.\n",
    "- __method__ (*str or list or None, optional*) The relaxation method used.  Allowed values are dynamic, static and box. Default value is dynamic (the most rigorous relaxation method).  All will be loaded if set to None.\n",
    "- __standing__ (*str or list or None, optional*) \"good\" records are the unique crystals found with the most rigorous relaxation, and with known prototypes over DFT structures.  \"bad\" are records filtered out, usually for being duplicates.  Default value is \"good\".  All will be loaded if set to None.\n",
    "- __family__ (*str or atomman.library.CrystalPrototype or list, optional*) The crystal family associated with the relaxed crystal - either crystal prototype name or MP/OQMD database entry name.\n",
    "- __parent_key__ (*str or list, optional*) The UUID4 key(s) assigned to the calculation that the record is based on.\n",
    "- __potential__ (*atomman.lammps.Potential or list, optional*) A loaded LAMMPS potential object to limit the search by.\n",
    "- __potential_LAMMPS_id__ (*str or list, optional*) The id for a LAMMPS implemented potential to limit the search by.\n",
    "- __potential_LAMMPS_key__ (*str or list, optional*) The UUID4 for a LAMMPS implemented potential to limit the search by.\n",
    "- __potential_id__ (*str or list, optional*) The id for a potential to limit the search by.\n",
    "- __potential_key__ (*str or list, optional*) The UUID4 for a potential to limit the search by.\n",
    "- __symbols__ (*str or list, optional*) Element symbols in the crystal to limit the search by.\n",
    "- __natypes__ (*int or list, optional*) The number of unique element model symbols in the crystal to limit the search by.\n",
    "- __natoms__ (*int or list, optional*) The number of unique atoms in the crystal's unit cell to limit the search by.\n",
    "\n",
    "Database option parameters\n",
    "\n",
    "- __database__ (*atomman.library.Database, optional*) A pre-defined Database object to use.  If not given, will initialize a new Database object.  Passing in a database can save time if multiple calls are made for the same record type. \n",
    "- __localpath__ (*str, optional*) The local library path to use when initializing a new Database.  IF not given, will use the default localpath.  Ignored if database is given. \n",
    "- __local__ (*bool, optional*) Indicates if the Database object is to look for local records.  Default is True.  Ignored if database is given.\n",
    "- __remote__ (*bool, optional*) Indicates if the Database object is to look for remote records.  Default is True.  Ignored if database is given.\n",
    "- __refresh_cache__ (*bool, optional*) If the local database is of style \"local\", indicates if the metadata cache file is to be refreshed.  If False, metadata for new records will be added but the old record metadata fields will not be updated.  If True, then the metadata for all records will be regenerated, which is needed to update the metadata for modified records.\n",
    "- __verbose__ (*bool, optional*) If True, info messages will be printed during operations.  Default value is False.\n",
    "\n",
    "Returns\n",
    "    \n",
    "- __system__ (*atomman.System*) The system object generated from the relaxed crystal."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Multiple matching record retrieved from remote\n",
      "#  family               symbols  alat    Ecoh    method  standing\n",
      " 1 A1--Cu--fcc          Al        4.0500 -3.3539 dynamic good\n",
      " 2 A1--Cu--fcc          Al        4.0500 -3.3539 dynamic good\n"
     ]
    },
    {
     "name": "stdin",
     "output_type": "stream",
     "text": [
      "Please select one: 1\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "avect =  [ 4.050,  0.000,  0.000]\n",
      "bvect =  [ 0.000,  4.050,  0.000]\n",
      "cvect =  [ 0.000,  0.000,  4.050]\n",
      "origin = [ 0.000,  0.000,  0.000]\n",
      "natoms = 4\n",
      "natypes = 1\n",
      "symbols = ('Al',)\n",
      "pbc = [ True  True  True]\n",
      "per-atom properties = ['atype', 'pos']\n",
      "     id |   atype |  pos[0] |  pos[1] |  pos[2]\n",
      "      0 |       1 |   0.000 |   0.000 |   0.000\n",
      "      1 |       1 |   0.000 |   2.025 |   2.025\n",
      "      2 |       1 |   2.025 |   0.000 |   2.025\n",
      "      3 |       1 |   2.025 |   2.025 |   0.000\n"
     ]
    }
   ],
   "source": [
    "ucell = am.load('crystal', potential_id='2003--Zope-R-R-Mishin-Y--Al', family='A1--Cu--fcc', symbols=['Al'])\n",
    "print(ucell)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    " "
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}
